package com.gobang.service;

import com.gobang.common.exception.ErrorCode;
import com.gobang.domain.message.*;

/**
 * 实时消息服务接口
 * 职责：WebSocket消息推送和转发，不处理任何业务逻辑
 * 
 * @author System
 * @since 1.0.0
 */
public interface MessageService {
    
    // ========== 消息推送功能（核心职责） ==========
    
    /**
     * 向指定用户发送消息
     *
     * @param userId 用户ID
     * @param message 消息对象
     */
    void sendToUser(Long userId, WebSocketMessage message);
    
    /**
     * 向房间内所有用户广播消息
     *
     * @param roomId 房间ID
     * @param message 消息对象
     */
    void broadcastToRoom(String roomId, WebSocketMessage message);
    
    /**
     * 发送匹配状态更新
     *
     * @param userId 用户ID
     * @param message 匹配状态更新消息
     */
    void sendMatchStatusUpdate(Long userId, MatchStatusUpdateMessage message);
    
    /**
     * 发送游戏状态更新
     *
     * @param roomId 房间ID
     * @param message 游戏状态更新消息
     */
    void sendGameStateUpdate(String roomId, GameStateUpdateMessage message);
    
    /**
     * 发送游戏结束通知
     *
     * @param roomId 房间ID
     * @param message 游戏结束通知消息
     */
    void sendGameOverNotification(String roomId, GameOverMessage message);
    
    /**
     * 发送匹配成功通知
     *
     * @param userId 用户ID
     * @param message 匹配成功通知消息
     */
    void sendMatchSuccessNotification(Long userId, MatchSuccessMessage message);
    
    /**
     * 发送对手离线通知
     *
     * @param roomId 房间ID
     * @param message 对手离线通知消息
     */
    void sendOpponentOfflineNotification(String roomId, OpponentOfflineMessage message);
    
    /**
     * 发送心跳消息
     *
     * @param userId 用户ID
     */
    void sendHeartbeat(Long userId);
    
    /**
     * 发送错误响应
     *
     * @param userId 用户ID
     * @param errorCode 错误码
     * @param message 错误消息
     */
    void sendErrorResponse(Long userId, ErrorCode errorCode, String message);
    
    // ========== 消息转发功能（不处理业务逻辑，仅转发） ==========
    
    /**
     * 转发落子请求到游戏核心模块，并推送处理结果
     * 职责：消息转发 + 结果推送，不处理游戏逻辑
     *
     * @param userId 用户ID
     * @param message 落子请求消息
     */
    void forwardMoveRequest(Long userId, MoveRequestMessage message);
    
    /**
     * 转发游戏状态请求到游戏核心模块，并推送查询结果
     * 职责：消息转发 + 结果推送，不处理游戏逻辑
     *
     * @param userId 用户ID
     * @param roomId 房间ID
     */
    void forwardGameStateRequest(Long userId, String roomId);
    
//    /**
//     * 转发匹配请求到匹配系统模块，并推送处理结果
//     * 职责：消息转发 + 结果推送，不处理匹配逻辑
//     *
//     * @param userId 用户ID
//     */
//    void forwardMatchRequest(Long userId);
//
//    /**
//     * 转发取消匹配请求到匹配系统模块，并推送处理结果
//     * 职责：消息转发 + 结果推送，不处理匹配逻辑
//     *
//     * @param userId 用户ID
//     */
//    void forwardCancelMatchRequest(Long userId);
} 